Skip to main content

Credential on File Workflow Guide

Introduction​

Recent payment network (Visa, MasterCard, Discover, American Express) changes to how payment cards are stored, and their use defined during authorization will impact all customers who store credit card accounts and process authorizations with those stored credit card accounts. Credential on File (CoF) is a workflow to store and use card information with authorization to take payments later.

EPS will transition availability for CoF with supported credit card processors as it becomes available. During the transition phase, the storage of a card account to the Payment Vault will support multiple workflow scenarios dependent upon CoF support. Integrators should not mix workflows, and once a supported processor becomes available the new workflow should be consumed.

Getting Started​

Here's what you'll do in this guide

  • Store and use a credit card payment account in Payment Vault using the CoF methods.
  • Update a credit card payment account using CoF.

Prerequisites needed before continuing

  • Your merchant must be setup to process card payments with one of the following:
    • The EPS Card Gateway
    • The Bridgepay/T-Gate network with First Data North
  • You will need to obtain your test credentials to try any of the examples in this guide. You should have received these from your Implementation Coordinator.
  • Review the Authentication guide for an understanding on how to authenticate to the EPS web service. This guide will walk you through sending a test connection and test credentials to ensure you are able to authenticate before moving forward.
  • Review the Vaulting Customer and Account Data guide on how to create customers and accounts used in this guide.
  • Download the Payment Vault WSDL file from the Downloads menu

Credential on File Workflow​

For this workflow we will walk through an example of how to register (vault) a credit card payment account and then make a payment on that account.

Understanding the Customer/Account Relationship

The CustomerNumber is what links the two records of customer and account. CustomerNumber and AccountReferenceID must be unique within the merchant (EntityID) and is chosen by the integrator.

CoF Guide

  • Step 1 The first thing that will need to occur is to capture the Required information needed to build the web request. For this example, we will use the following information:
    • Account Type : Visa
    • Name on Account : Test Customer
    • Product ID : A1234 from product selection
    • Account Number : 4111111111111111
    • Expiration Date(mm/yy) : 12/24
    • Account Nickname (optional) : My Visa
    • Location for the authorization : 1234
  • Step 2 Using the collected information, we will populate a RegisterCardAccount request for the existing customer 123456789. We will include a unique AccountReferenceID of 111222333444567 for this account. We will store the AccountReferenceID in our front-end database as it uniquely identifies the account in the EPS vault and will be needed for other method calls.

Here is our RegisterCardAccount request for this example:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pv="https://ssl.selectpayment.com/PV">
   <soapenv:Header>
      <pv:SecurityHeader>
         <pv:BinarySecurityToken>your security token here</pv:BinarySecurityToken>
      </pv:SecurityHeader>
   </soapenv:Header>
   <soapenv:Body>
    <pv:RegisterCardAccount>
        <pv:storeId>0</pv:storeId>
        <pv:storeKey isNull="true" />
        <pv:entityId>entityId of your merchant</pv:entityId>
        <pv:locationId>1234</pv:locationId>
        <pv:account>
            <pv:CustomerNumber>123456789</pv:CustomerNumber>
            <pv:AccountType>Visa</pv:AccountType>
            <pv:NameOnAccount>Test Customer</pv:NameOnAccount>
            <pv:AccountName>My Visa</pv:AccountName>
            <pv:AccountNumber>111111111111111</pv:AccountNumber>
            <pv:ExpirationMonth>12</pv:ExpirationMonth>
            <pv:ExpirationYear>24</pv:ExpirationYear>
            <pv:AccountReferenceID>111222333444567</pv:AccountReferenceID>
        </pv:account>
    </pv:RegisterCardAccount>
	</soapenv:Body>
</soapenv:Envelope>

When the request is sent, EPS will send a verification authorization prior to storing the credit card account. Per payment network rules, if the verification authorization fails, the credit card account cannot be stored. A verification authorization is a transaction that must correctly be associated with a merchant processing account (LID).

  • Step 3 We should get a successful response back indicating the account was created like the example below. Store the AccountReferenceId to use in later methods.

Here is the successful response for this example:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <soap:Body>
    <RegisterCardAccount>
        <MethodParameters>
                <WSUpdateResult>
                <returnValue>Success</returnValue>
                <message>Operation successful</message>
                </WSUpdateResult>
        </MethodParameters>
    </RegisterCardAccount>
    </soap:Body>
</soap:Envelope>
  • Step 4 Now, to make a payment using a stored CoF credit card account, we will need to use the method SaleFromCardAccount. Unique to this workflow we need to define how the authorization is being used in the "storedCredential" parameter. For this example, we will gather the following information to populate the request and say that a customer has initiated an unscheduled internet payment using the stored card.
    • Amount : 25.00 purchase amount.
    • Stored Card Account : 111222333444567
    • CCVS : 3123
    • StoredCredential : Customer

Here is our SaleFromCardAccount request for this example:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pv="https://ssl.selectpayment.com/PV">
   <soapenv:Header>
      <pv:SecurityHeader>
         <pv:BinarySecurityToken>your security token here</pv:BinarySecurityToken>
      </pv:SecurityHeader>
   </soapenv:Header>
   <soapenv:Body>
    <pv:SaleFromCardAccount>
        <pv:storeId>0</pv:storeId>
        <pv:storeKey isNull="true" />
        <pv:entityId>entityId of your merchant</pv:entityId>
        <pv:locationId>locationId of the transaction</pv:locationId>
        <pv:accountReferenceId>111222333444567</pv:accountReferenceId>
        <pv:paymentOrigin>Internet</pv:paymentOrigin>
        <pv:Amount>25.00</pv:Amount>
        <pv:terminalNumber>__WebService</pv:terminalNumber>
        <pv:TransactionNumber>112</pv:TransactionNumber>
        <pv:Description> </pv:Description>
        <pv:Field1></pv:Field1>
        <pv:Field2></pv:Field2>
        <pv:Field3></pv:Field3>
        <pv:CCVS>3123</pv:CCVS>
        <pv:clientIP></pv:clientIP>
        <pv:storedCredential>Customer</pv:storedCredential>
    </pv:SaleFromCardAccount>
	</soapenv:Body>
</soapenv:Envelope>
  • Step 5 We should get a successful response back indicating the transaction was successful like the example below. Be sure to log the key items from the response.
    • ReferenceNumber – EPS generates this value for you to use for pulling reporting information on the transaction later. You will want to store this number with the transaction in your database.
    • Success – indicates a successful transaction.
    • Error – indicates if an error has occurred.
    • ResponseCode – EPS code signifying result of the request.
    • ActualDate – when the transaction was created in EPS.
    • ResponseMessage – detailed description for the response code when applicable.

Here is our successful response for this example:

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
	<SaleFromCardAccountResponse xmlns="https://ssl.selectpayment.com/PV">
		<SaleFromCardAccountResult>
				<ReferenceNumber>T:82Q1Y1A7A2L</ReferenceNumber>
				<Success>true</Success>
				<Error>false</Error>
				<ResponseCode>Success</ResponseCode>
				<ActualDate>2010-12-30T00:00:00.0000000-06:00</ActualDate>
				<ResponseMessage>Success</ResponseMessage>
				<OriginatedAs>Card_Transfer</OriginatedAs>
		</SaleFromCardAccountResult>
	</SaleFromCardAccountResponse>
 </soap:Body>
</soap:Envelope>

Update Credential on File Workflow​

The purpose of this operation is to make any corrections, additions or changes to a customer's Card account information. This method is specifically intended to be used with Credential on File. When this method is used, an account verification will occur behind the scenes prior to updating the account number.

  • Step 1 To update a card with CoF we will need to use the UpdateCardAccount method and capture the updated account information to build the web request. For this example, we will use the following information:
    • Account Type : Visa
    • Name on Account : Test Customer
    • Account Number : 4111111111111112
    • Expiration Date(mm/yy) : 12/24
    • Account Nickname (optional) : My Visa
    • Location for the authorization : 1234
  • Step 2 Using the collected information, we will populate an UpdateCardAccount request for the existing account 111222333444567. All elements in this operation should have a value supplied even if that element isn't changing or required. Any element left blank or not included in the request will either update a field without data or override any existing data already in that field.
    note

    If the CustomerNumber element is left blank or not included in the request, the account will no longer be associated with the original customer and a new system generated one will be assigned.

Here is our UpdateCardAccount request for this example:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:pv="https://ssl.selectpayment.com/PV">
   <soapenv:Header>
      <pv:SecurityHeader>
         <pv:BinarySecurityToken>your security token here</pv:BinarySecurityToken>
      </pv:SecurityHeader>
   </soapenv:Header>
   <soapenv:Body>
    <pv:UpdateCardAccount>
        <pv:storeId>0</pv:storeId>
        <pv:storeKey isNull="true" />
        <pv:entityId>entityId of your merchant</pv:entityId>
        <pv:locationId>your locationId</pv:locationId>
        <pv:accountRefId>111222333444567</pv:accountRefId>
        <pv:account>
            <pv:CustomerNumber>123456789</pv:CustomerNumber>
            <pv:AccountType>Visa</pv:AccountType>
            <pv:NameOnAccount>Test Customer</pv:NameOnAccount>
            <pv:AccountName>My Visa</pv:AccountName>
            <pv:AccountNumber>4111111111111122</pv:AccountNumber>
            <pv:ExpirationMonth>12</pv:ExpirationMonth>
            <pv:ExpirationYear>24</pv:ExpirationYear>
            <pv:AccountReferenceID>111222333444567</pv:AccountReferenceID>
        </pv:account>
    </pv:UpdateCardAccount>
	</soapenv:Body>
</soapenv:Envelope>

Under certain conditions a verification authorization will be sent prior to performing the update. Per payment network rules, if the verification authorization fails, the credit card account cannot be updated. A verification transaction will only occur if the Account Number is changed or there is no CoF data associated to the account. As with registering the card account, the authorization must correctly be associated with a merchant processing account (LID).

  • Step 5 We should get a successful response back indicating the update was successful like the example below.

Here is our successful response for this example:

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
    <UpdateCardAccount>
        <MethodParameters>
            <WSUpdateResult>
                <returnValue>Success</returnValue>
                <message>Operation successful</message>
            </WSUpdateResult>
        </MethodParameters>
    </UpdateCardAccount>
</soap:Body>
</soap:Envelope>

Handling Errors and Failed Requests​

Not all requests will be successful, so we will need to run through a few common errors you should be ready to handle.

  • Duplicate Account - Duplicate account requests will be unsuccessful. Duplicate records are determined based on AccountReferenceId for accounts. These values must be unique within a merchant and if a duplicate is attempted you will receive a message in your response like shown below. To handle this situation, a unique value will need to be selected before sending another attempt.
    <returnValue>Error_UniqueConstraint</returnValue>
    <message>The operation failed due to a unique constraint.</message>

  • Authorization Failed - The verification authorization sent when storing or updating the card account can fail for the reasons listed below. For all of these scenarios, the values will need to be checked for inaccuracies and fixed before resubmitting.

    • For Register Card Account Method.

      If the Account number is already registered

    <returnValue>Error_UniqueConstraint</returnValue>
    <message>The operation failed due to a unique constraint.</message>
  • Invalid Account number
  <returnValue>Error_Unknown</returnValue>
  <message>The AccountNumber (xxxxxx1732) is not a valid Account Number.</message>
  • An Invalid Expiration year.
  <returnValue>Error_Unknown</returnValue>
  <message>Please provide a valid Expiration Year for the Credit Card.</message>

  • For Update Card Account Method

    An Invalid AccountReferenceId

  <returnValue>Error_DoesNotExist</returnValue>
  <message>The specified account (ZZZZff096374-3eba-4e56-93c9-2924d4b7e982), does not exist</message>

Timeout waiting for response - Systems should be designed to wait 5 seconds to receive a response before timing out. If a timeout occurs, you can attempt to retry registering the account again. If you receive the unique constraint message in response to the retry, that will indicate that the original attempt was either successful or had already existed.

Next Steps​

  • Customize the workflows to fit your specific business needs.
    • You can apply the principles shown in these examples and customize the requests using the API Reference to suit your needs by adding more custom fields or other card account types for other customers.
  • Review the API Reference
    • This guide is just a starting point to show how to work with credit card Credential on File. Please review the API Reference to see all APIs and their technical specifications.
  • Explore other guides
    • We have other guides to show how to leverage our APIs in other common use cases so if this one doesn't cover what you are looking for, give another guide a try.
  • Get certified and move into production
    • Ready to put your new code into production use? Refer to this process guide that explains our certification steps and how to contact us to get started.